[% setvar title Add C<header> and C<unheader> funtions to core distribution %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Add <code>header</code> and <code>unheader</code> funtions to core distribution</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>   Maintainer: Nathan Wiger &lt;<a href='mailto:nate@wiger.org'>nate@wiger.org</a>&gt;
   Date: 27 Sep 2000
   Last Modified: 29 Sep 2000
   Mailing List: <a href='mailto:perl6-stdlib@perl.org'>perl6-stdlib@perl.org</a>
   Number: 333
   Version: 2
   Status: Frozen</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Many services use HTTP-style headers to pass information, including
HTTP, SMTP, and others. These headers, described in internet RFC 822
(see <i><a href='http://search.cpan.org/perldoc?REFERENCES'>REFERENCES</a></i>), are a widely-accepted internet standard.</p>
<p>This RFC proposes that Perl include a simple function, <code>header</code>, that
can be used to interact with these headers more easily. It is a
general-purpose formatting function that does not do any
content-specific handling (unlike <code>CGI.pm</code>'s version). It is also
proposed that an <code>unheader</code> function be included which converts in the
opposite direction.</p>
<a name='NOTES ON FREEZE'></a><h1>NOTES ON FREEZE</h1>
<p>Since this belongs in a module, and I've already written one, this RFC
basically boils down to just making sure Text::Header (or an equivalent
yet renamed module) ends up in the stdlib. These functions just need to
be available for stuff like the <code>use cgi</code> pragma proposed in <b>RFC
288</b>.</p>
<p>Any additional technical concerns should be addressed towards improving
the module itself.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>The <code>header</code> function works very similarly to <code>CGI.pm</code> and
<code>HTTP::Headers</code>:</p>
<pre>   @HEADERS = header(content_type =&gt; 'text/html',
                     author =&gt; 'Nathan Wiger',
                     last_modified =&gt; $date,
                     accept =&gt; [qw(text/html text/plain)]);</pre>
<p>This would produce an array of the following:</p>
<pre>   @HEADERS = (&quot;Content-Type: text/html\n&quot;,
               &quot;Author: Nathan Wiger\n&quot;,
               &quot;Last-Modified: Wed Sep 27 13:31:06 PDT 2000\n&quot;,
               &quot;Accept: text/html, text/plain\n&quot;);</pre>
<p>Note that unlike <code>CGI.pm</code>, the header function does not end the array
with a singular &quot;\n&quot;. The <code>header</code> function would simply:</p>
<pre>   1. uc the first letter of each tag token and lc the
      rest, also converting _'s to -'s automatically

   2. Add a colon separating each tag and its value,
      and exactly one newline after each one

   3. Combine list elements into a comma-delimited
      string </pre>
<p>This usage integrates very well with <b>RFC 288</b> on improving the
coupling between Perl and CGI apps. Note that a list is always joined
into a comma-delimited string. To insert multiple separate headers,
simply call <code>header</code> with multiple args:</p>
<pre>   push @out, header(accept =&gt; 'text/html',
                     accept =&gt; 'text/plain');</pre>
<p>This would create multiple &quot;Accept:&quot; lines.</p>
<p>Unlike <code>CGI.pm</code>, the <code>header</code> function would <b>not</b> provide any
defaults. If called simply as:</p>
<pre>   @HEADERS = header;</pre>
<p><code>header</code> will return an empty list. This allows <code>header</code> to be more
general pupose, so it can provide SMTP and other headers as well:</p>
<pre>   @mail_headers = header(from =&gt; '<a href='mailto:nate@sun.com'>nate@sun.com</a>',
                          to =&gt; '<a href='mailto:perl6-rfc@perl.org'>perl6-rfc@perl.org</a>');
   print $MAIL @mail_headers, &quot;\n&quot;, @content;</pre>
<p>In addition, it is proposed that an <code>unheader</code> function be added as
well. This function would convert in the opposite direction:</p>
<pre>   1. lc the entire tag name converting -'s to _'s

   2. Separate each tag based on the colon delimiter,
      chomping newlines.

   3. Return a list of tag/value pairs for easy assignment
      to a hash</pre>
<p>So, assuming the <code>@HEADERS</code> array above:</p>
<pre>   %myheaders = unheader(@HEADERS);</pre>
<p>The hash <code>%myheaders</code> would have the following values:</p>
<pre>   %myheaders = (
       content_type =&gt; 'text/html',
       author =&gt; 'Nathan Wiger',
       last_modified =&gt; 'Wed Sep 27 13:31:06 PDT 2000',
       accept =&gt; 'text/html, text/plain'
   );</pre>
<p>Note that all keys are converted to lowercase, and their values have
their newlines stripped. However, note that comma-separated fields are
not split up on input. This cannot be done reliably because some fields,
such as the HTTP &quot;Date:&quot; header, can contain commas even though they are
not lists. Inferring this type of structure would require knowledge of
content, and these functions are specifically designed to be
content-independent</p>
<p>Since the two functions are inverses, this:</p>
<pre>   @out = header unheader @in;</pre>
<p>will result in <code>@out</code> being exactly equivalent to <code>@in</code>.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>Include <code>Text::Header</code> in the stdlib:
<a href='http://www.perl.com/CPAN/modules/by-authors/id/N/NW/NWIGER/Text-Header-1.03.tar.gz' target='_blank'>www.perl.com</a></p>
<a name='MIGRATION'></a><h1>MIGRATION</h1>
<p>This introduces new functionality, but its name does conflict with those
using <code>CGI.pm</code>. However, using both <code>CGI.pm</code> and <code>Text::Header</code> at
the same time would silly, so would probably not happen.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 288: First-Class CGI Support</p>
<p>RFC 14:  Modify open() to support FileObjects and Extensibility</p>
<p><code>CGI.pm</code> by Lincoln Stein</p>
<p><code>HTTP::Headers</code> by Gisle Aas</p>
<p><a href='http://sunsite.auc.dk/RFC/rfc/rfc822.html' target='_blank'>sunsite.auc.dk</a></p>
</div>
